QUICKDRAW™ 3D Rendering Acceleration Virtual Engine RAVE SDK 1.0.6/GM
APPLE COMPUTER, 3/28/96
WHAT IS "QUICKDRAW 3D RAVE"?
QuickDraw 3D RAVE is a low-level abstraction layer for 3D hardware accelerators. Because RAVE is an abstraction layer, it provides a common layer which can be used to access a variety of different hardware accelerators. RAVE also provides a default software rasterizer which is always available, even on systems that don't have a hardware accelerator installed.
The QuickDraw 3D Interactive Renderer uses RAVE to do all interactive rendering. As a result, QuickDraw 3D automatically works with any hardware accelerator which has a RAVE plug-in.
RAVE 1.04 is shipping now as part of QuickDraw 3D 1.04.
ABOUT THIS RELEASE
This is the GM release of RAVE 1.0.6 which is the first simultaneous release on PowerMacintosh and Windows™ 95.
This software has passed all of Apple's quality assurance tests. In the unlikely event that RAVE problems occur during your development please report bugs to RAVE's Technical Lead:
Brent Pease
APPLELINK: PEASE
email: brent@apple.com
RAVE DISTRIBUTION
RAVE is being distributed in the form of a DDK (Device Driver Kit) and a SDK(Software Developers Kit). The DDK is primarily for hardware vendors who are developing 3D accelerators to run with QuickDraw 3D. The SDK is primarily for game developers who need direct access to low level 3D rasterization functions such as texture mapping and z-buffered drawing.
If you wish to distribute RAVE with your application on either Macintosh™ or Windows™ 95 please contact:
Shawn Hopwood
Apple Computer
One Infinite Loop
Cupertino, CA 95014
email: s.hopwood@applelink.apple.com
WHEN SHOULD YOU USE RAVE AS AN API?
— If you are a game developer who has already written an optimized 3D rendering engine, directly accessing RAVE will likely be the easiest way for you to add support for 3D acceleration to your games.
— If you want to use a 3D accelerator for non-3D tasks (e.g. video compositing).
— If you have a 3D API or engine and would like to access 3D acceleration.
REASONS _NOT_ TO USE RAVE AS AN API
— RAVE is just a rasterization layer, QuickDraw 3D is much easier to use and has far more functionality than RAVE. RAVE exposes many peculiarities of the windowing and hardware which are difficult to deal with cleanly, particularly for applications which must work with multiple monitors, all pixel formats, etc.
— Do NOT use RAVE because it's "faster than going through QuickDraw 3D" — it isn't. The QuickDraw 3D Interactive Renderer uses RAVE extremely efficiently; you won't gain ANY advantage by going "directly to the low-level calls".
— Do NOT use RAVE because it provides features that QuickDraw 3D does not support (e.g. different Z buffering modes, color pixmaps, Z buffer-less drawing). QuickDraw 3D 1.1 will provide all these features through the high-level API.
— Do NOT use RAVE because QuickDraw 3D doesn't have good datatypes for games. We are adding several new datatypes to QuickDraw 3D 1.1 which are excellent for game rendering, so you should at least learn about what's coming before starting to do your own.
WHAT'S IN THIS SDK?
This SDK contains the GM 1.0.6 release of QuickDraw 3D RAVE. It contains all the header files and shared libraries needed to write and debug software that uses RAVE. Additionally it contains documentation in ERS(Engineering Requirements Document) form, final documention will be available in a future release.
The contents of this SDK were all developed using the Metrowerks™ development environment, from the CW8 CD. We recommend an on-line reference for Macintosh programming (e.g. the ThinkC™ Reference or QuickView™) as well, particularly if you're not an experienced Macintosh programmer.
WHAT'S NEW IN 1.05
This release contains two new APIs, the TriMesh and support for color lookup tables. These APIs are documented in the ERS that has been distributed with this release. Final documentation for RAVE will be available soon.
The name of the plug-in has changed from QuickDraw 3D Acceleration Layer to QuickDraw 3D RAVE.
RAVE_TEST
RAVE_Test is an application written for devlopers of RAVE engines, however we felt that it is an useful enough example of how to get started using RAVE to be included here. RAVE_Test opens two windows, one using the built software engine, the other using another engine such as a hardware accelerator. If another engine is not available the second window will be empty. Click the mouse to run through the various tests.
RAVE_Test runs tests that draw points, lines, Gouraud triangles and texture triangles. Each test is run four ways: Single buffered, double buffered, single buffered with 2D clipping, and double buffered with 2D clipping.
GAME SCENE
This bare-bones sample application shows how to use the low-level RAVE API for drawing screen-space triangles. It renders a single game-like scene using texture maps and bitmaps. It also demonstrates how to convert PICT files into RAVE textures and bitmaps.
When Game Scene is launched, it looks for the monitor that supports the greatest number of colors. On that display it opens a square window, into which it draws the scene. When it has finished drawing, you can exit the app by clicking the mouse.
Game Scene has pretty good error-handling, but if it does encounter a problem, it will not display any sort of error message. It will simply exit. Time to fire up your source-level debugger!
Note that the 10 PICT files included with Game Scene must be in the same folder as the application. If it cannot find them, it will simply quit.
As shipped, the Game Scene app will not use Apple's QuickDraw™ 3D Hardware Acceleration card if it is installed. To enable support for this card, you must uncomment a line in main(), in GSApp.c. See that file for details. All other RAVE-compliant accelerators should be handled automatically.
QUICKDRAW™ 3D RAVE
"QuickDraw™ 3D RAVE" is a shared library that contains the RAVE manager and Apple's software rasterizer. You need to link with it whenever you are making RAVE calls. Two versions are included, in two folders called "QD3D RAVE (debug on)" and "QD3D RAVE (debug off)". The debug on version does extensive parameter and semantic checking of all RAVE calls; this is particularly useful when you are developing application code that drives RAVE. The debug off version is the optimized release, and performs no (or minimal) validation checking.
APPLE SOFTWARE RASTERIZER
This release includes "QuickDraw™ 3D RAVE" version 1.0.5, which includes a software plug-in which implements a complete (although basic) RAVE feature set. Some notes on the software rasterizer features:
— Rendering to any GDevice, and to 16 or 32 bit memory devices is supported. Rendering is optimized for 16 and 32 bit deep GDevices; all others are supported by rendering 16 bits offscreen and then blitting.
— Texture mapping is point-sampled from the closest mipmap level.
HEADERS
This folder holds the RAVE.h header file, as described by the RAVE ERS. RAVE.h should be included by application code that uses RAVE. Note that Drive3D.h has been included for backwards compatibility and it simply #includes RAVE.h.
USING SHARED LIBRARIES
Your preferred "QuickDraw™ 3D RAVE" library (i.e. with or without debugging) needs to be either in your application's folder (usually the most convenient for development) or in the System Extensions folder. The same is true of your drawing engine shared library (if present). In this SDK we've placed a copy of the debug-on "QuickDraw™ 3D RAVE" library in the application folder, so right now the RAVE_Test application is being run with debug on.
